@poppinss/request

Request

Wrapper over Node.js req object to standardize and ease the process of reading data from HTTP requests.

Table of contents

• Features
• Usage
• Config
• Typescript support
• API
• Maintainers

Features

• Support for reading plain and signed cookies (only when signed via @poppinss/response)
• Handy methods for content negotiation.
• Handles inconsistencies between certain headers like referer and referrer.
• Reliably reads ip address of proxied requests.
• Assigns distributed unique x-request-id to each request.

Usage

Install the package from npm as follows:

npm i @poppinss/request

# yarn
yarn add @poppinss/request

and then use it as follows

import { Request, RequestConfigContract } from '@poppinss/request'
import { createServer } from 'http'

const config: RequestConfigContract = {
  allowMethodSpoofing: false,
  subdomainOffset: 2,
  trustProxy: require('proxy-addr').compile('loopback'),
}

createServer((req, res) => {
  const request = new Request(req, res, config)
  res.end(`${request.id()} ${request.url()}`)
})

Config

{
"allowMethodSpoofing": false	Since, standard HTML forms doesn't allow all HTTP verbs like PUT, DELETE and so on. The allowMethodSpoofing allows defining the HTTP method as a query string _method. When allowMethodSpoofing = true and current request method is POST, then request.method() will give preference to the query string _method property, over the original request method.
"subdomainOffset": 2	Offset indicates the number of values to remove from the end of the URL seperated by .. For example: For URL indicative.adonisjs.com, the request.subdomains() method will return an array with ['indicative'].
"trustProxy"	A method that allows you to selectively trust the proxy servers. Make sure to read proxy-addr docs.
"getIp"	Optionally define a method to determine the user Ip adress. The method is helpful, when you want to rely on a different property to find the user ip address. For example: Nginx set x-real-ip header when used a proxy server. In that case you can define your own getIp method for same. getIp (request) { // I am using nginx as a proxy server and want to trust 'x-real-ip' return request.header('x-real-ip') }
"secret"	Optional Define a secret to unsign and read cookies. Make sure you have used the same secret to sign the cookie via @poppinss/response package.
}

Typescript support

The module is written in Typescript and exports following classes, types and interfaces.

import { Request, RequestContract, RequestConfigContract} from '@poppinss/request'

RequestContract is the interface that Request class adheres too. Since, you cannot extend concrete implementations in Typescript, you may need the interface to have a lossely typed flow.

Request.macro('cartValue', function () {
  return Number(this.cookie('cart')) || 0
})

then, you need to add cartValue to the interface

import { RequestContract as BaseContract } from '@poppinss/request'

interface RequestContract extends BaseContract {
  cartValue (): number
}

const request = new Request(req, res, config) as unknown as RequestContract

API

Following are the autogenerated files via Typedoc

• API

Maintainers

Harminder virk